

    \filetitle{simulate}{Simulate model}{model/simulate}

	\paragraph{Syntax}\label{syntax}

\begin{verbatim}
S = simulate(M,D,Range,...)
[S,Flag,AddF,Discrep] = simulate(M,D,Range,...)
\end{verbatim}

\paragraph{Input arguments}\label{input-arguments}

\begin{itemize}
\item
  \texttt{M} {[} model {]} - Solved model object.
\item
  \texttt{D} {[} struct \textbar{} cell {]} - Input database or datapack
  from which the initial conditions and shocks from within the
  simulation range will be read.
\item
  \texttt{Range} {[} numeric {]} - Simulation range.
\end{itemize}

\paragraph{Output arguments}\label{output-arguments}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \texttt{S} {[} struct \textbar{} cell {]} - Database with simulation
  results.
\end{itemize}

\paragraph{Output arguments in non-linear
simulations}\label{output-arguments-in-non-linear-simulations}

\begin{itemize}
\item
  \texttt{Flag} {[} cell \textbar{} empty {]} - Cell array with exit
  flags for non-linearised simulations.
\item
  \texttt{AddF} {[} cell \textbar{} empty {]} - Cell array of tseries
  with final add-factors added to first-order approximate equations to
  make non-linear equations hold.
\item
  \texttt{Discrep} {[} cell \textbar{} empty {]} - Cell array of tseries
  with final discrepancies between LHS and RHS in equations marked for
  non-linear simulations by a double-equal sign.
\end{itemize}

\paragraph{Options}\label{options}

\begin{itemize}
\item
  \texttt{'anticipate='} {[} \emph{\texttt{true}} \textbar{}
  \texttt{false} {]} - If \texttt{true}, real future shocks are
  anticipated, imaginary are unanticipated; vice versa if
  \texttt{false}.
\item
  \texttt{'contributions='} {[} \texttt{true} \textbar{}
  \emph{\texttt{false}} {]} - Decompose the simulated paths into
  contributions of individual shocks.
\item
  \texttt{'deviation='} {[} \texttt{true} \textbar{}
  \emph{\texttt{false}} {]} - Treat input and output data as deviations
  from balanced-growth path.
\item
  \texttt{'dbOverlay='} {[} \texttt{true} \textbar{}
  \emph{\texttt{false}} \textbar{} struct {]} - Use the function
  \texttt{dboverlay} to combine the simulated output data with the input
  database, or with another database, at the end.
\item
  \texttt{'dTrends='} {[} \emph{\texttt{@auto}} \textbar{} \texttt{true}
  \textbar{} \texttt{false} {]} - Add deterministic trends to
  measurement variables.
\item
  \texttt{'ignoreShocks='} {[} \texttt{true} \textbar{}
  \emph{\texttt{false}} {]} - Read only initial conditions from input
  data, and ignore any shocks within the simulation range.
\item
  \texttt{'plan='} {[} plan {]} - Specify a simulation plan to swap
  endogeneity and exogeneity of some variables and shocks temporarily,
  and/or to simulate some of the non-linear equations accurately.
\item
  \texttt{'progress='} {[} \texttt{true} \textbar{}
  \emph{\texttt{false}} {]} - Display progress bar in the command
  window.
\end{itemize}

\paragraph{Options in nonlinear
simualations}\label{options-in-nonlinear-simualations}

\begin{itemize}
\item
  \texttt{'addSstate='} {[} \emph{\texttt{true}} \textbar{}
  \texttt{false} {]} - Add steady state levels to simulated paths before
  evaluating non-linear equations; this option is used only if
  \texttt{'deviation=' true}.
\item
  \texttt{'display='} {[} \emph{\texttt{true}} \textbar{} \texttt{false}
  \textbar{} numeric \textbar{} Inf {]} - Report iterations on the
  screen; if \texttt{'display=' N}, report every \texttt{N} iterations;
  if \texttt{'display=' Inf}, report only final iteration.
\item
  \texttt{'error='} {[} \texttt{true} \textbar{} \emph{\texttt{false}}
  {]} - Throw an error whenever a non-linear simulation fails converge;
  if \texttt{false}, only an warning will display.
\item
  \texttt{'lambda='} {[} numeric \textbar{} \emph{\texttt{1}} {]} - Step
  size (between \texttt{0} and \texttt{1}) for add factors added to
  non-linearised equations in every iteration.
\item
  \texttt{'reduceLambda='} {[} numeric \textbar{} \emph{\texttt{0.5}}
  {]} - Factor (between \texttt{0} and \texttt{1}) by which
  \texttt{lambda} will be multiplied if the non-linear simulation gets
  on an divergence path.
\item
  \texttt{'maxIter='} {[} numeric \textbar{} \emph{\texttt{100}} {]} -
  Maximum number of iterations.
\item
  \texttt{'tolerance='} {[} numeric \textbar{} \emph{\texttt{1e-5}} {]}
  - Convergence tolerance.
\end{itemize}

\paragraph{Description}\label{description}

\subparagraph{Output range}\label{output-range}

Time series in the output database, \texttt{S}, are are defined on the
simulation range, \texttt{Range}, plus include all necessary initial
conditions, i.e.~lags of variables that occur in the model code. You can
use the option \texttt{'dboverlay='} to combine the output database with
the input database (i.e.~to include a longer history of data in the
simulated series).

\subparagraph{Deviations from steady-state and deterministic
trends}\label{deviations-from-steady-state-and-deterministic-trends}

By default, both the input database, \texttt{D}, and the output
database, \texttt{S}, are in full levels and the simulated paths for
measurement variables include the effect of deterministic trends,
including possibly exogenous variables. The default behavior can be
changed by changing the options \texttt{'deviation='} and
\texttt{'dTrends='}.

The default value for \texttt{'deviation='} is false. If set to
\texttt{true}, then the input database is expected to contain data in
the form of deviations from their steady state levels or paths. For
ordinary variables (i.e.~variables whose log status is \texttt{false}),
it is $x_t-\Bar x_t$, meaning that a 0 indicates that the variable is at
its steady state and e.g.~2 indicates the variables exceeds its steady
state by 2. For log-variables (i.e.~variables whose log status is
\texttt{true}), it is $x_t/\Bar x_t$, meaning that a 1 indicates that
the variable is at its steady state and e.g.~1.05 indicates that the
variable is 5 per cent above its steady state.

The default value for \texttt{'dTrends='} is \texttt{@auto}. This means
that its behavior depends on the option \texttt{'deviation='}. If
\texttt{'deviation=' false} then deterministic trends are added to
measurement variables, unless you manually override this behavior by
setting \texttt{'dTrends=' false}. On the other hand, if
\texttt{'deviation=' true} then deterministic trends are not added to
measurement variables, unless you manually override this behavior by
setting \texttt{'dTrends=' true}.

\subparagraph{Simulating contributions of
shocks}\label{simulating-contributions-of-shocks}

Use the option \texttt{'contributions=' true} to request the
contributions of shocks to the simulated path for each variable; this
option cannot be used in models with multiple alternative
parameterizations or with multiple input data sets.

The output database, \texttt{S}, contains Ne+2 columns for each
variable, where Ne is the number of shocks in the model:

\begin{itemize}
\item
  the first columns 1\ldots{}Ne are the contributions of the Ne
  individual shocks to the respective variable;
\item
  column Ne+1 is the contribution of initial condition, th econstant,
  and deterministic trends, including possibly exogenous variables;
\item
  column Ne+2 is the contribution of nonlinearities in nonlinear
  simulations (it is always zero otherwise).
\end{itemize}

The contributions are additive for ordinary variables (i.e.~variables
whose log status is \texttt{false}), and multplicative for log varibles
(i.e.~variables whose log status is \texttt{true}). In other words, if
\texttt{S} is the output database from a simulation with
\texttt{'contributions=' true}, \texttt{X} is an ordinary variable, and
\texttt{Z} is a log variable, then

\begin{verbatim}
sum(S.X,2)
\end{verbatim}

(i.e.~the sum of all Ne+2 contributions in each period, i.e.~summation
goes across 2nd dimension) reproduces the final simulated path for the
variable \texttt{X}, whereas

\begin{verbatim}
prod(S.Z,2)
\end{verbatim}

(i.e.~the product of all Ne+2 contributions) reproduces the final
simulated path for the variable \texttt{Z}.

\subparagraph{Simulations with multiple parameterisations and/or
multiple data
sets}\label{simulations-with-multiple-parameterisations-andor-multiple-data-sets}

If you simulate a model with \texttt{N} parameterisations and the input
database contains \texttt{K} data sets (i.e.~each variable is a time
series with \texttt{K} columns), then the following happens:

\begin{itemize}
\item
  The model will be simulated a total of \texttt{P = max(N,K)} number of
  times. This means that each variables in the output database will have
  \texttt{P} columns.
\item
  The 1st parameterisation will be simulated using the 1st data set, the
  2nd parameterisation will be simulated using the 2nd data set, etc.
  until you reach either the last parameterisation or the last data set,
  i.e. \texttt{min(N,K)}. From that point on, the last parameterisation
  or the last data set will be simply repeated (re-used) in the
  remaining simulations.
\item
  Put formally, the \texttt{I}-th column in the output database, where
  \texttt{I = 1, ..., P}, is a simulation of the \texttt{min(I,N)}-th
  model parameterisation using the \texttt{min(I,K)}-th input data set
  number.
\end{itemize}

\paragraph{Example}\label{example}


